/*
 * Copyright 2002-2015 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.springframework.session.web.http;

import java.util.List;

import javax.servlet.http.Cookie;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
 * Strategy for reading and writing a cookie value to the
 * {@link HttpServletResponse}.
 *
 * @author Rob Winch
 * @since 1.1
 */
public interface CookieSerializer {

	/**
	 * Writes a given {@link CookieValue} to the provided
	 * {@link HttpServletResponse}
	 *
	 * @param cookieValue
	 *            the {@link CookieValue} to write to
	 *            {@link CookieValue#getResponse()}. Cannot be null.
	 */
	void writeCookieValue(CookieValue cookieValue);

	/**
	 * Reads all the matching cookies from the {@link HttpServletRequest}. The
	 * result is a List since there can be multiple {@link Cookie} in a single
	 * request with a matching name. For example, one Cookie may have a path of
	 * / and another of /context, but the path is not transmitted in the
	 * request.
	 *
	 * @param request
	 *            the {@link HttpServletRequest} to read the cookie from. Cannot
	 *            be null.
	 * @return the values of all the matching cookies
	 */
	List<String> readCookieValues(HttpServletRequest request);

	/**
	 * Contains the information necessary to write a value to the
	 * {@link HttpServletResponse}.
	 *
	 * @author Rob Winch
	 * @since 1.1
	 */
	public class CookieValue {
		private final HttpServletRequest request;
		private final HttpServletResponse response;
		private final String cookieValue;

		/**
		 * Creates a new instance
		 *
		 * @param request
		 *            the {@link HttpServletRequest} to use. Useful for
		 *            determining the context in which the cookie is set. Cannot
		 *            be null.
		 * @param response
		 *            the {@link HttpServletResponse} to use.
		 * @param cookieValue
		 *            the value of the cookie to be written. This value may be
		 *            modified by the {@link CookieSerializer} when writing to
		 *            the actual cookie so long as the original value is
		 *            returned when the cookie is read.
		 */
		public CookieValue(HttpServletRequest request, HttpServletResponse response, String cookieValue) {
			this.request = request;
			this.response = response;
			this.cookieValue = cookieValue;
		}

		/**
		 * Gets the request to use.
		 * @return the request to use. Cannot be null.
		 */
		public HttpServletRequest getRequest() {
			return request;
		}

		/**
		 * Gets the response to write to.
		 * @return the response to write to. Cannot be null.
		 */
		public HttpServletResponse getResponse() {
			return response;
		}

		/**
		 * The value to be written. This value may be modified by the {@link CookieSerializer} before written to the cookie. However, the value must be the same as the original when it is read back in.
		 *
		 * @return the value to be written
		 */
		public String getCookieValue() {
			return cookieValue;
		}
	}
}
